home *** CD-ROM | disk | FTP | other *** search
/ Logiciels PC Special 3 / Logiciel PC - Hors-Serie 3.iso / Logs / micros / ql / outils / qltoolsq / source / docs / qltools24.readme < prev    next >
Text File  |  1995-09-21  |  25KB  |  797 lines
  1.                  QLTOOLS v2.4
  2.                  ============
  3. What is it
  4. ----------
  5.  
  6. This document describes the features and limitations of the program
  7. qltools v2.4.
  8.  
  9. qltools v2.4 is a program for systems such as Linux, Windows NT, OS/2
  10. and MSDOS (and Win95) to read and write floppy disks in the 'QL5A' or
  11. 'QL5B' format used by the QDOS operating system and its clones and
  12. near-siblings such as SMS2, SMSQ, SMSQ/E and most other things
  13. starting SMS.
  14.  
  15. qltools can be compiled for and should run on other Unix systems. It
  16. will also handle disk images under VAX/VMS, but this is not included
  17. in the distribution.
  18.  
  19. qltools v2.4 is based on the qltools program of Giuseppe
  20. Zanetti, with modifications by Valenti Omar and Richard Zidlicky.
  21.  
  22. v2.4 has been almost entirely rewritten by Jonathan R Hudson.
  23.  
  24. Features
  25. --------
  26.  
  27.     o Fully supports level 2 directory operations
  28.     o Supports DD (720K) and HD (1440K) disks
  29.     o Supports disk images on all platforms.
  30.     o Read, write, delete files
  31.     o Create, delete sub-directories
  32.     o Initialise disks in SMS/QDOS format
  33.     o Dump disk sectors in ASCII or binary
  34.     o Display disk map
  35.  
  36. Changes from earlier versions
  37. -----------------------------
  38.  
  39. The support for level 2 sub-directories has resulted in almost a
  40. completely re-written program. Some options that were previously
  41. available (but didn't seem to work) have been removed. For example, I
  42. never got the the deleted file recovery to work, this functionality is
  43. now available via binary dump of sectors; I can verify that this does
  44. work !
  45.  
  46. Files are now only referred to by name, the level 2 scheme for
  47. enumerating files in sub-directories having made the previous file
  48. numbering scheme impractical.
  49.  
  50. Disk Images
  51. -----------
  52.  
  53. Users of previous versions of 'qltools' under Unix may be familiar
  54. with the concept of a disk image created using the dd (1) program and
  55. well documented in Giuseppe's original manual. This functionality is
  56. now available to DOS (for DOS read MSDOS/Win95/OS2/NT) users.
  57.  
  58. A disk image is a verbatim copy of an SMS/QDOS disk stored in a hard
  59. disk file. All operations that can be performed on an actual floppy
  60. can also be performed on the disk image. The disk image can be
  61. transferred back to floppy disk, thus making multiple changes to a
  62. disk much faster. Due to restrictions in my current DOS compiler and
  63. the Win95 floppy disk driver, Win95 long file names can only be used
  64. with disk images and not floppy disks. Long file names are supported
  65. for both disk images and floppies under Unix, NT and OS/2.
  66.  
  67. Disk images are created under DOS using the supplied 'qdc'
  68. (Quintessential Disk Cloner) program as follows:
  69.  
  70. QDC
  71. ---
  72.  
  73. qdc -d dtest.dsk    Creates a blank hard disk file 'dtest.dsk',
  74.             ready for initialising as a SMS/QDOS DD disk
  75.             image (720Kb).
  76.  
  77. qdc -h HTest.dsk    Creates a blank hard disk file 'HTest.dsk',
  78.             ready for initialising as a SMS/QDOS HD disk
  79.             image (1440Kb).
  80.  
  81. qdc a: atest.dsk    Creates a hard disk image file from the
  82.             SMS/QDOS format floppy disk in drive 'A'.
  83.  
  84. qdc btest.dsk b:    Copies the hard disk image file to the floppy
  85.             disk in drive 'B'. The disk must be formatted
  86.             (under either DOS, Unix or SMS/QDOS). Any data
  87.             on the disk will be overwritten.
  88.  
  89. Notes:
  90.  
  91. a. disk images created with 'qdc' -d and -h options must be
  92.    initialised (qltools -f) before they can be used
  93.  
  94.    e.g.      qltools dtest.dsk -fd "DD Image"
  95.          qltools HTest.dsk -fh "HD Image"
  96.   
  97. b. 'qdc' does not check that disk image file sizes and floppy disks
  98.    are of compatible sizes; you do that !
  99.  
  100.  
  101. Using Long Files Names
  102. ----------------------
  103.  
  104. 'qltools' v2.4 supports long files to both disk images and floppy
  105. disks when run under Linux, (Unix), Windows NT and OS/2 operating
  106. systems.
  107.  
  108. The MSDOS version of qltools only supports MSDOS 8.3 names, which is
  109. limiting, particularly for sub-directories. If you are running Windows
  110. 95, you can use 'qltools' and long files TO DISK IMAGES ONLY by
  111. running the NT version of the program. Note that the NT version of
  112. 'qltools' will not access floppy disks when run under Win95 due to the
  113. emasculated drivers/Win32 API in Win95.
  114.  
  115. Using 'qltools'
  116. ---------------
  117.  
  118. qltools is invoked as:
  119.  
  120. qltools dev_name option [files]
  121.  
  122. where dev_name is either a device name or the name of a disk image
  123. file.
  124.  
  125. Device Names
  126. ------------
  127.  
  128. The device names supported are:
  129.  
  130. MSDOS, OS/2:
  131.  
  132.     a:
  133.     b:
  134.  
  135. NT
  136.  
  137.     \\.\a: 
  138.     \\.\b: 
  139.  
  140. Linux
  141.  
  142.     /dev/fd0H720
  143.     /dev/fd0H1440
  144.  
  145.     or as a shorthand
  146.  
  147.         fd=/dev/fd0H720
  148.         hd=/dev/fd0H1440
  149.         export fd
  150.         export hd
  151.         qltools $hd ..etc..
  152.  
  153. Other Unix
  154.  
  155.     as documented for your system
  156.  
  157. Options
  158. -------
  159.  
  160. The following options are supported.
  161.  
  162. -d            list directory
  163. -s            list short directory
  164. -i            list info
  165. -m            list disk map
  166. -c            list conversion table of sectors
  167. -w <name>        write <name> file to disk, query overwrite
  168. -W <name>        write <name> file to disk, no query
  169. -x <name> <size>    make <name> executable with dataspace=size
  170. -r <name>        remove file <name>
  171. -n <name>        copy file <name> to stdout
  172. -fxx <name>        format as xx=hd|dd disk with label <name>
  173. -l            list names as written
  174. -uN            dumps cluster N (1536 bytes) to stdout in
  175.             ASCII format.
  176. -UN            dumps cluster N (1536 bytes) to stdout as
  177.             raw (binary) data.
  178. -M <dirname>        creates level 2 directory <dirname>
  179.  
  180.  
  181. The following descriptions assume a Linux implementation, substitute
  182. a: (or \\.\a:) for DOS/OS2 or NT disks or a disk image name.  The
  183. Linux shell prompt in the examples is "bash#".
  184.  
  185. Option -d
  186. ---------
  187.  
  188. Lists a QDOS directory, in the following format:
  189. (Note comment markers in [square brackets]).
  190.  
  191. bash# qltools $fd -d
  192.  
  193. qltools 24                                [1]
  194. 1086/1440 sectors.                            [2]
  195.  
  196. copyright                                1389 18/09/95 17:06:54 v0    [3]
  197. dterm                               (dir) 64                [4]
  198. dterm_x_dat                              4839 18/09/95 17:06:54 v0    
  199. dtest                               (dir) 384
  200. dtest_dsub                          (dir) 128
  201. dtest_dsub_a_bas                          177 18/09/95 17:06:56 v0    
  202. dtest_dsub_b_bas                          177 18/09/95 17:06:56 v0    
  203. dtest_x_bas                               177 18/09/95 17:06:56 v0    
  204. dtest_x_bat                               177 18/09/95 17:06:57 v0    
  205. dtest_x_dat                              4839 18/09/95 17:06:57 v0    
  206. dtest_x_yyy                               177 18/09/95 17:06:57 v0    
  207. dtest_y_bas                               177 18/09/95 17:06:58 v0    
  208. echoOn_bas                                 80 18/09/95 17:06:58 v0    
  209. echooff_bas                                83 18/09/95 17:06:58 v0    
  210. exit_bas                                   47 18/09/95 17:06:58 v0    
  211. fax                                 (dir) 128
  212. fax_bas                                   501 18/09/95 17:06:58 v0    
  213. fax_basic                           (dir) 128
  214. fax_basic_this_is_an_extremely_long1      759 18/09/95 17:06:58 v0    
  215. fax_basic_what_a_long_one                 759 18/09/95 17:06:59 v0    
  216. makefile                                  298 18/09/95 17:06:59 v0    
  217. qltools_c                               34641 18/09/95 17:06:59 v0    
  218. testsub                             (dir) 64
  219. testsub_subfile                     (dir) 64
  220. testsub_subfile_test                     4839 18/09/95 17:07:04 v0    
  221. unzip                               E   91400 18/09/95 17:07:05 v0     (40268)
  222.  
  223.  
  224. Notes:
  225.  
  226. [1] The volume label for the disk, set the SMS/QDOS format or qltools
  227.     -f option.
  228.  
  229. [2] The used and good sectors
  230.  
  231. [3] A file listing. This consists of
  232.  
  233.     name
  234.     type (blank if zero)
  235.         E    - executable
  236.         R    - relocatable
  237.         (dir)    - level 2 directory
  238.         (NNN)   - unrecognised type NNN
  239.  
  240.     file size in bytes
  241.     date of last update
  242.     time of last update
  243.     version number (I count from 0).
  244.  
  245.     (data space)    - for type 'E'
  246.  
  247. [4] Level 2 directories are marked (dir) and show the size.
  248.  
  249. Note that the above selection was compiled to test various options of
  250. qltools and InfoZIP and is unrepresentative of anything else !
  251.  
  252. Option -s
  253. ---------
  254.  
  255. Lists a directory in short format, note that directories are listed
  256. to, this is because qltools can will copy this to native format in
  257. such a way that they can be re-created on the QDOS device on
  258. re-copy. This is described in the '-n' and '-w/-W' options.
  259.  
  260. bash# qltools $fd -s
  261. copyright
  262. dterm                            [1]
  263. dterm_x_dat
  264. dtest
  265. dtest_dsub
  266. dtest_dsub_a_bas
  267. dtest_dsub_b_bas
  268. dtest_x_bas
  269. dtest_x_bat
  270. dtest_x_dat
  271. dtest_x_yyy
  272. dtest_y_bas
  273. echoOn_bas
  274. echooff_bas
  275. exit_bas
  276. fax
  277. fax_bas
  278. fax_basic
  279. fax_basic_this_is_an_extremely_long1
  280. fax_basic_what_a_long_one
  281. makefile
  282. qltools_c
  283. testsub
  284. testsub_subfile                        [2]
  285. testsub_subfile_test
  286. unzip
  287.  
  288. Notes:
  289.  
  290. [1] This is the name of a directory
  291. [2] So is this !
  292.  
  293.  
  294. Option -i
  295. ---------
  296.  
  297. This lists information about the disk.
  298.  
  299. bash# qltools $fd -i
  300. Disk ID          : QL5A
  301. Disk Label       : qltools 24
  302. sectors per track: 9
  303. sectors per cyl. : 18
  304. number of cylind.: 80
  305. allocation block : 3
  306. sector offset/cyl: 5
  307. random           : 6ed6
  308. Updates          : 27
  309. free sectors     : 1086
  310. good sectors     : 1440
  311. total sectors    : 1440
  312. directory is     : 1 sectors and 256 bytes
  313.  
  314. logical-to-physical sector mapping table:
  315.  
  316. 0 3 6 80 83 86 1 4 7 81 84 87 2 5 8 82 85 88 
  317.  
  318. physical-to-logical sector mapping table:
  319.  
  320. 0 6 c 1 7 d 2 8 e 3 9 f 4 a 10 5 b 11 
  321.  
  322.  
  323. 'qltools' write a random number when it initialises a disk (-f), and
  324. updates the update field when a file is updated or deleted.
  325.  
  326. Option -m
  327. ---------
  328.  
  329. This lists the disk map. To save space, I'll only illustrate a small
  330. portion of it.
  331.  
  332. bash# qltools $fd -m | more
  333.  
  334. block   file    pos
  335.  
  336. 0       3968    0       (f80, 000) map
  337. 1       0       0       (000, 000) directory
  338. 2       1       0       (001, 000) copyright
  339. 3       2       0       (002, 000) dterm
  340. 4       2052    0       (804, 000) 
  341. 5       2052    1       (804, 001) 
  342. 6       2052    2       (804, 002) 
  343. 7       2052    3       (804, 003) 
  344. 8       3       0       (003, 000) dtest
  345. 9       2057    0       (809, 000) 
  346. 10      2058    0       (80a, 000) 
  347. 11      2059    0       (80b, 000) 
  348. 12      2060    0       (80c, 000) 
  349. 13      2061    0       (80d, 000) 
  350. 14      2062    0       (80e, 000) 
  351. 15      2062    1       (80e, 001) 
  352. 16      2062    2       (80e, 002) 
  353. 17      2062    3       (80e, 003) 
  354. 18      2066    0       (812, 000) 
  355. 19      2067    0       (813, 000) 
  356. 20      4       0       (004, 000) echoOn_bas
  357. 21      5       0       (005, 000) echooff_bas
  358. 22      6       0       (006, 000) exit_bas
  359. 23      7       0       (007, 000) fax
  360. 24      2072    0       (818, 000) 
  361. 25      2073    0       (819, 000) 
  362. 26      2074    0       (81a, 000) 
  363. 27      2075    0       (81b, 000) 
  364. 28      8       0       (008, 000) makefile
  365. 29      9       0       (009, 000) qltools_c
  366. 30      9       1       (009, 001) qltools_c
  367. 31      9       2       (009, 002) qltools_c
  368. 32      9       3       (009, 003) qltools_c
  369. 33      9       4       (009, 004) qltools_c
  370. 34      9       5       (009, 005) qltools_c
  371. --More--
  372.  
  373.  
  374. The file numbers OR'd with 0x800 are files in level two
  375. sub-directories. You can follow the directory threads by dumping (-u)
  376. the directory sectors, for example, -u8 to dump the cluster containing
  377. the 'dtest' sub-directory. Note that the file numbers recorded in the
  378. sub-directory records are one greater that the values in the map.
  379.  
  380. For example, the entry in dtest for dtest_x_bas has the file number as
  381. 0x80d in the directory record; in the map this corresponds to 0x80c,
  382. started in cluster 12. This is shown in the -u example.
  383.  
  384. Option -c
  385. ---------
  386.  
  387. The -c option lists the conversion table converting QDOS logical
  388. sector (clusters of 3x512 byte disk blocks) to physical address.  Note
  389. that the physical sector numbers (as per the SMS/QDOS manual) start at
  390. 0, when doing direct sector addressing, sectors start at 1.  The
  391. unix_dev value can be used (*512) as input to lseek(2).
  392.  
  393. bash# qltools $fd -c | more
  394.  
  395. CONVERSION TABLE
  396.  
  397. logic   track   side    sector  unix_dev
  398.  
  399. 0       0       0       0       0
  400. 1       0       0       3       3
  401. 2       0       0       6       6
  402. 3       0       1       0       9
  403. 4       0       1       3       12
  404. 5       0       1       6       15
  405. 6       0       0       1       1
  406. 7       0       0       4       4
  407. 8       0       0       7       7
  408. 9       0       1       1       10
  409. 10      0       1       4       13
  410. 11      0       1       7       16
  411. 12      0       0       2       2
  412. 13      0       0       5       5
  413. 14      0       0       8       8
  414. 15      0       1       2       11
  415.  
  416. Option -x
  417. ---------
  418.  
  419. Sets the data space for executable (type 1) files. Note that 'qltools'
  420. automatically records dataspace sizes for executable files created by
  421. the Lux68 and XTc68 cross compilers and programs copied from SMS/QDOS
  422. disks.
  423.  
  424. For example, if we had not recorded the dataspace size for 'unzip',
  425. then it could be set by:
  426.  
  427.     qltools $fd -x unzip 40268 
  428.     or
  429.     qltools a: -x unzip 40268    DOS/OS2
  430.     qltools \\.\a: unzip 40268    NT
  431.  
  432.  
  433. Option -r
  434. ---------
  435.  
  436. This option deletes files. Sub-directory files can only be deleted
  437. when the directory is empty.
  438.  
  439.     qltools $fd -r unzip        # delete unzip program
  440.  
  441.     qltools $fd -r dtest        # fails !
  442.  
  443.     Giving the message:
  444.  
  445.     Directory must be empty to delete (8)
  446.  
  447. The number in brackets (8) is the number of files in the directory
  448. (and its sub-directories)
  449.  
  450. Option -n
  451. ---------
  452.  
  453. The -n option writes files to stdout (standard output). This may be
  454. redirected using the '>' notation. For DOS and friends the file is
  455. 'binary' (i.e. no end of line translation). If the file is a
  456. subdirectory, then a 'special' file is written that is 16 bytes long
  457. and contains the text
  458.  
  459.     qltools:type255
  460.     
  461. followed by a LF character. For example, the following 'Perl' script
  462. (qlcp.pl) copies all the files off our example floppy into the current
  463. (linux) directory.
  464.  
  465.     #!/usr/bin/perl
  466.     # Perl script to copy all files from a QL DD disk under Linux
  467.     # _ in QDOS file names are changed to .
  468.     # usage : qlcp device
  469.  
  470.     $dev = $ARGV[0];
  471.  
  472.     open (QL, "qltools $dev -s |");
  473.     while (<QL>)
  474.     {
  475.         chomp;
  476.         $unx = $_;
  477.         $unx =~ s/_/\./g;
  478.         system "qltools $dev $_ >$unx";
  479.     }
  480.     close (QL);
  481.  
  482. Translating the SMS/QDOS '_' to '.'.
  483.  
  484. Listing the linux directory gives:
  485.  
  486. bash# ls -l
  487. total 163
  488. -rw-r--r--   1 root     root         1389 Sep 19 22:41 copyright
  489. -rw-r--r--   1 root     root           16 Sep 19 22:41 dterm
  490. -rw-r--r--   1 root     root         4839 Sep 19 22:41 dterm.x.dat
  491. -rw-r--r--   1 root     root           16 Sep 19 22:41 dtest
  492. -rw-r--r--   1 root     root           16 Sep 19 22:41 dtest.dsub
  493. -rw-r--r--   1 root     root          177 Sep 19 22:41 dtest.dsub.a.bas
  494. -rw-r--r--   1 root     root          177 Sep 19 22:41 dtest.dsub.b.bas
  495. -rw-r--r--   1 root     root          177 Sep 19 22:41 dtest.x.bas
  496. -rw-r--r--   1 root     root          177 Sep 19 22:41 dtest.x.bat
  497. -rw-r--r--   1 root     root         4839 Sep 19 22:41 dtest.x.dat
  498. -rw-r--r--   1 root     root          177 Sep 19 22:41 dtest.x.yyy
  499. -rw-r--r--   1 root     root          177 Sep 19 22:41 dtest.y.bas
  500. -rw-r--r--   1 root     root           80 Sep 19 22:41 echoOn.bas
  501. -rw-r--r--   1 root     root           83 Sep 19 22:41 echooff.bas
  502. -rw-r--r--   1 root     root           47 Sep 19 22:41 exit.bas
  503. -rw-r--r--   1 root     root           16 Sep 19 22:41 fax
  504. -rw-r--r--   1 root     root          501 Sep 19 22:41 fax.bas
  505. -rw-r--r--   1 root     root           16 Sep 19 22:41 fax.basic
  506. -rw-r--r--   1 root     root          759 Sep 19 22:41 fax.basic.this.is.an.extremely.long1
  507. -rw-r--r--   1 root     root          759 Sep 19 22:41 fax.basic.what.a.long.one
  508. -rw-r--r--   1 root     root          298 Sep 19 22:41 makefile
  509. -rw-r--r--   1 root     root        34641 Sep 19 22:41 qltools.c
  510. -rw-r--r--   1 root     root           16 Sep 19 22:41 testsub
  511. -rw-r--r--   1 root     root           16 Sep 19 22:41 testsub.subfile
  512. -rw-r--r--   1 root     root         4839 Sep 19 22:41 testsub.subfile.test
  513. -rw-r--r--   1 root     root        91408 Sep 19 22:41 unzip
  514.  
  515.  
  516. Note the 16 byte directory markers.
  517.  
  518. If this directory tree is then copied back to an SMS/QDOS disk or disk
  519. image.
  520.  
  521. bash# dd of=../demo.dsk if=/dev/zero count=1440 bs=512    # create blank
  522. bash# qltools ../demo.dsk -fd Qlone            # initialise
  523. bash# qltools ../demo.dsk -w *                # populate
  524.  
  525. The the first bit of the directory looks like:
  526.  
  527. bash# qltools ../demo.dsk -d
  528. Qlone     
  529. 1086/1440 sectors.
  530.  
  531. copyright                                1389 19/09/95 22:53:16 v0    
  532. dterm                               (dir) 64
  533. dterm_x_dat                              4839 19/09/95 22:53:16 v0    
  534.  
  535. Note that the 'dterm' level 2 directory has been automagically
  536. created.
  537.  
  538. Note also that if no other options are given, then the -n option can
  539. be omitted.
  540.  
  541.     qltools a: test_bas >test.bas    ; for DOSsers.
  542.  
  543.  
  544.     qltools $fd qltools_c        # == cat qltools_c
  545.  
  546. Option -f
  547. ---------
  548.  
  549. This option initialises a disk or disk image. A floppy disk must have
  550. been low-level formatted first using the SMS/QDOS 'format' or the
  551. DOS/NT/OS2 'format' command, or the equivalent for Unix (Linux
  552. 'fdformat' command). As qltools always records the number of good
  553. sectors as the maximum the media supports, I recommend that you always
  554. verify foreign formats and only use known good disks.
  555.  
  556. bash# fdformat $fd
  557. Double-sided, 80 tracks, 9 sec/track. Total capacity 720 kB.
  558. Formatting ... done
  559. Verifying ... done
  560. bash# qltools $fd -fd 'SMS/QDOS !'
  561. bash# qltools $fd -i
  562. Disk ID          : QL5A
  563. Disk Label       : SMS/QDOS !
  564. sectors per track: 9
  565. sectors per cyl. : 18
  566. number of cylind.: 80
  567. allocation block : 3
  568. sector offset/cyl: 5
  569. random           : 15da
  570. Updates          : 1
  571. free sectors     : 1434
  572. good sectors     : 1440
  573. total sectors    : 1440
  574. directory is     : 0 sectors and 64 bytes
  575.  
  576. logical-to-physical sector mapping table:
  577.  
  578. 0 3 6 80 83 86 1 4 7 81 84 87 2 5 8 82 85 88 
  579.  
  580. physical-to-logical sector mapping table:
  581.  
  582. 0 6 c 1 7 d 2 8 e 3 9 f 4 a 10 5 b 11 
  583.  
  584. The '-f' must be followed IMMEDIATELY by 'd' for DD disks or 'h' for
  585. HD disks, and the media name.
  586.  
  587. Option -u, -U
  588. -------------
  589.  
  590. The -u command dumps a logical 'sector' (a cluster of three physical
  591. sectors) to stdout. Given the example for '-m' (map info), we saw that
  592. the 'dtest' directory was in logical sector 8. Dumping logical sector
  593. 8 gives.
  594.  
  595. bash# qltools $fd -u8 | more
  596. 000 :  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
  597. 010 :  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
  598. 020 :  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
  599. 030 :  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
  600. 040 :  00 00 00 c0 00 ff 00 00 00 00 00 00 00 00 00 0a  ................
  601. 050 :  64 74 65 73 74 5f 64 73 75 62 00 00 00 00 00 00  dtest_dsub......
  602. 060 :  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
  603. 070 :  00 00 00 00 41 4b 19 b0 00 00 08 0a 41 4b 19 af  ....AK......AK..
  604. 080 :  00 00 00 f1 00 00 00 00 00 00 00 00 00 00 00 0b  ................
  605. 090 :  64 74 65 73 74 5f 78 5f 62 61 73 00 00 00 00 00  dtest_x_bas.....
  606. 0a0 :  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
  607. 0b0 :  00 00 00 00 41 4b 19 b0 00 00 08 0d 41 4b 19 b0  ....AK......AK..
  608. 0c0 :  00 00 00 f1 00 00 00 00 00 00 00 00 00 00 00 0b  ................
  609. 0d0 :  64 74 65 73 74 5f 78 5f 62 61 74 00 00 00 00 00  dtest_x_bat.....
  610. 0e0 :  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
  611. 0f0 :  00 00 00 00 41 4b 19 b1 00 00 08 0e 41 4b 19 b1  ....AK......AK..
  612. (and more)
  613.  
  614. The first column is offset (hex), then the hex data followed by ASCII
  615. representation of printable characters.
  616.  
  617. The file dtest_x_bas has a file number recorded [from *(short *)0x0ba]
  618. as 080d (hex). Subtract 0x801 as this is a sub-directory record, and
  619. the logical cluster number is 0xc (i.e. 12), and the file number in
  620. the map will be 0x80c (see -m example again).
  621.  
  622. We could now dump out this file (from logical sector 12) as
  623.  
  624. bash# qltools $fd -u12 | more
  625. 000 :  00 00 00 f1 00 00 00 00 00 00 00 00 00 00 00 0b  ................
  626. 010 :  64 74 65 73 74 5f 78 5f 62 61 73 00 00 00 00 00  dtest_x_bas.....
  627. 020 :  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
  628. 030 :  00 00 00 00 41 4b 19 b0 00 00 08 0d 41 4b 19 b0  ....AK......AK..
  629. 040 :  31 30 20 43 4c 49 45 4e 54 20 27 71 74 70 69 27  10 CLIENT 'qtpi'
  630. 050 :  0a 32 30 20 52 45 51 55 45 53 54 20 27 71 74 70  .20 REQUEST 'qtp
  631. 060 :  69 27 2c 27 77 61 6b 65 27 0a 33 30 20 52 45 4d  i','wake'.30 REM
  632. 070 :  61 72 6b 20 52 45 51 55 45 53 54 20 27 71 74 70  ark REQUEST 'qtp
  633. 080 :  69 27 2c 27 64 69 61 6c 20 6a 72 68 27 2c 61 24  i','dial jrh',a$
  634. 090 :  0a 33 33 20 52 45 51 55 45 53 54 20 27 71 74 70  .33 REQUEST 'qtp
  635. 0a0 :  69 27 2c 27 73 70 61 77 6e 20 66 6c 70 31 5f 6a  i','spawn flp1_j
  636. 0b0 :  64 27 2c 61 24 0a 33 35 20 42 45 45 50 20 32 30  d',a$.35 BEEP 20
  637. 0c0 :  30 30 2c 32 30 20 3a 20 50 52 49 4e 54 20 27 73  00,20 : PRINT 's
  638. 0d0 :  70 61 77 6e 20 3d 20 27 3b 61 24 0a 34 30 20 46  pawn = ';a$.40 F
  639. 0e0 :  52 45 45 43 4c 49 45 4e 54 20 27 71 74 70 69 27  REECLIENT 'qtpi'
  640. 0f0 :  0a 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
  641.  
  642. If this file had been accidentally deleted, we could have 'rescued' it
  643. using the -U command to dump the logical sectors to stdout. Had the
  644. file been more than one logical sector, this would have to have been
  645. done multiple times, getting the file sector numbers from the map
  646. (80c,000), (80c,001) etc.
  647.  
  648.  
  649. bash# qltools $fd -U12       
  650. ±
  651. AK░10 CLIENT 'qtpi'
  652. 20 REQUEST 'qtpi','wake'
  653. 30 REMark REQUEST 'qtpi','dial jrh',a$
  654. 33 REQUEST 'qtpi','spawn flp1_jd',a$
  655. 35 BEEP 2000,20 : PRINT 'spawn = ';a$
  656. 40 FREECLIENT 'qtpi'
  657.  
  658. Note that there is some rubbish at the beginning of the dumped file as
  659. 'qltools' dumps complete logical sectors of 1536 bytes.
  660.  
  661. As a further example, the 'dterm' directory is is logical sector 3,
  662. dumping this reveals the file 'dterm_x_dat' starts in logical sector
  663. 4; from the map (-m) it can be seen that this file occupies logical
  664. sectors 4,5,6,7 (file number 0x804).
  665.  
  666. Options -w, -W and -l
  667. ---------------------
  668.  
  669. These options control the writing of files to the SMS/QDOS disk or
  670. disk image. 'qltools' converts any '.'s in the native file names to
  671. '_' when the files are written to the SMS/QDOS disk.
  672.  
  673. The '-w' option queries for file overwrites.
  674.  
  675. bash# qltools demo.dsk -w qltools.c
  676. file qltools_c exists, overwrite [Y/N/A/Q] : N
  677.  
  678. The '-W' option copies file without prompting for overwrite.
  679. The '-l' option lists (to stderr) file names as they are copied.
  680.  
  681. Wildcards are supported on all platforms for write commands.
  682.  
  683. bash# qltools $fd -l -W *
  684.  
  685. or (just in case we have an OS/2 aficionado)
  686.  
  687. [C:\] qltools a: -l -W *.*
  688.  
  689. qltools strips any Unix or DOS-ish directory names from the file
  690. before it is written to the SMS/QDOS disk.
  691.  
  692. i.e.
  693.  
  694.     ~/test/demofile.txt    ----->        demofile_txt
  695.  
  696. Option -M
  697. ---------
  698.  
  699. The -M command makes level 2 sub-directories. This works like the
  700. level 2 MAKE_DIR. Any files that 'match' will be moved into the
  701. sub-directory.
  702.  
  703. Given a file test_file (or even test.file) (on the foreign disk), then
  704.  
  705. bash# qltools $fd -w test_file        # write file
  706. bash# qltools $fd -d            # check it
  707. test_file                                 293 19/09/95 23:35:20 v0
  708. bash# qltools $fd -M test        # create dir
  709. bash# qltools $fd -d            # check it
  710. test                                (dir) 64
  711. test_file                                 293 19/09/95 23:35:20 v0
  712.  
  713. Just for fun, we could have done.
  714.  
  715. bash# qltools $fd -M test        # create dir
  716. bash# qltools $fd -d            # check it
  717. test                                (dir) 0
  718. bash# qltools $fd -w test_file        # write file
  719. bash# qltools $fd -d            # check it
  720. test                                (dir) 64
  721. test_file                                 293 19/09/95 23:35:20 v0
  722.  
  723. i.e. Exactly the same.
  724.  
  725. As many qltools commands can follow on the command line, we could also
  726. have done:
  727.  
  728. bash# qltools $fd -w test_file -M test
  729.  or
  730. bash# qltools $fd -M test -w test_file
  731.  
  732. The effect of the two command is essentially the same.
  733.  
  734. And if the 'special' file 'test' contained the magic 16 characters
  735. "qltools:type255\n", then 
  736.  
  737. bash# qltools $fd -w test -w test_file
  738. and
  739. bash# qltools $fd -w test_file -w test
  740.  
  741. Would also have the same effect.
  742.  
  743. and to delete it again !!!
  744. bash# qltools demo.dsk -r test_file -r test
  745. BUT NOT
  746. bash# qltools demo.dsk -r test -r test_file    # Why not ??
  747. Directory must be empty to delete (1)        # Of course !
  748.  
  749.  
  750. Distribution
  751. ------------
  752.  
  753. qltools is copyright (c)  Giuseppe Zanetti
  754. The level 2 and system specific bits are (c) Jonathan Hudson
  755.  
  756. The software is freely distributable.
  757.  
  758. In order to minimise the inconvenience to users who are just
  759. interested in a specific platform, qltools is distributed as follows:
  760.  
  761. qltools24src.zip
  762.     Source code and documentation for all platforms.
  763.  
  764. qltools24Linux.zip
  765.     Binary and docs for Linux
  766.  
  767. qltools24DOS.zip
  768.     16 bit binary and docs for MSDOS
  769.  
  770. qltools24NT.zip
  771.     32 bit binary and docs for Windows NT
  772.  
  773. qltools24OS2.zip
  774.     32 bit binary and docs for OS/2.
  775.  
  776.  
  777. Compiling
  778. ---------
  779.  
  780. qltools 2.4 compiles without errors or warnings using gcc 2.6.3 on
  781. Linux and Watcom C/C++ 10.0 on DOS/NT/OS2. It also compiles on DOS
  782. using Borland C 3.1.
  783.  
  784. Note that the 'wildargv' code linked into the distributed DOS/NT/OS2
  785. binaries is (c) Watcom and cannot be distributed. Similar code is
  786. available for other compilers.
  787.  
  788. Keeper of the code
  789. ------------------
  790.  
  791. The qltools code is currently maintained by:
  792.  
  793. Jonathan R Hudson, PO Box 2272, Ruwi 112, Sultanate of Oman.
  794.  
  795. Tel/Fax : +968 699407 (24 hours)
  796. BBS    : +968 699407 (18:00-03:00 GMT)
  797.